\chapter{The Elements of a Assembly Language Program}
\label{chapter:elements}

\section{Assembly Language Statements}

Introduce the assembly language grammar. 
\begin{itemize}
\item Statement = 1 line of text containing an instruction or directive.
\item Instruction = label, mnemonic, operands, comment.
\item Directive = Used to control the operation of the assembler.
\end{itemize}

\section{Memory Layout}

Is this a good place to introduce the text, data, bss, heap and stack regions?

Or does that belong in a new section/chapter that discusses addressing modes?


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{A Sample Program Source Listing}

A simple program that illustrates how this text presents 
program source code is seen in \listingRef{zero4regs.S}.
This program will place a zero in each of the 4 registers 
named x28, x29, x30 and x31.

\listing{zero4regs.S}{Setting four registers to zero.}

This program listing illustrates a number of things: 
\begin{itemize}
\item Listings are identified by the name of the file within which
	they are stored.  This listing is from a file named: \verb@zero4regs.S@.
\item The assembly language programs discussed in this text will be saved
	in files that end with: \verb@.S@  (Alternately you can use \verb@.sx@ 
	on systems that don't understand the difference between upper and 
	lowercase letters.\footnote{The author of this text prefers to avoid
	using such systems.})
\item A description of the listing's purpose appears under the name of the
	file.  The description of \listingRef{zero4regs.S} is 
	{\em Setting four registers to zero.}
\item The lines of the listing are numbered on the left margin for
	easy reference.
\item An assembly program consists of lines of plain text.
\item The RISC-V ISA does not provide an operation that will simply 
	set a register to a numeric value.  To accomplish our goal this
	program will add zero to zero and place the sum in in each of the
	four registers.
\item The lines that start with a dot `.' (on lines 1, 2 and 3) are 
	called {\em assembler directives} as they tell the assembler itself
	how we want it to translate the following {\em assembly language instructions} 
	into {\em machine language instructions.}  
\item Line 4 shows a {\em label} named {\em \_start}.  The colon
	at the end is the indicator to the assembler that causes it to
	recognize the preceding characters as a label.
\item Lines 5-8 are the four assembly language instructions that
	make up the program.  Each instruction in this program
	consists of four {\em fields}.  (Different instructions can have 
	a different number of fields.)  The fields on line 5 are:

	\begin{itemize}
	\item [addi] The instruction mnemonic.  It indicates the operation 
		that the CPU will perform.
	\item [x28] The {\em destination} register that will receive the 
		sum when the {\em addi} instruction is finished.  The names of
		the 32 registers are expressed as x0 -- x31.
	\item [x0] One of the addends of the sum operation.  (The x0 register
		will always contain the value zero.  It can never be changed.)
	\item [0] The second addend is the number zero.
		\item [\# set \ldots] Any text anywhere in a RISC-V assembly language
	program that starts with the pound-sign is ignored by the assembler.
			They are used to place a {\em comment} in the program to help
	the reader better understand the motive of the programmer.
	\end{itemize}
\end{itemize}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Running a Program With rvddt}
\index{rvddt}

To illustrate what a CPU does when it executes instructions this text
will use the \gls{rvddt} simulator to display shows sequence of events 
and the binary values involved.  This simulator supports the RV32I ISA 
and has a configurable amount of memory.%
\footnote{The {\em rvddt} simulator was written to generate the listings for 
this text.  It is similar to the fancier {\em spike} simulator.  
Given the simplicity of the RV32I ISA, rvddt is less than 1700 lines of C++ 
and was written in one (long) afternoon.}

\listingRef{zero4regs.out} shows the operation of the four 
{\em addi} instructions from \listingRef{zero4regs.S} when it is executed
in trace-mode.

\listing{zero4regs.out}{Running a program with the rvddt simulator}

\begin{itemize}
\item [$\ell$ 1] This listing includes the command-line that shows how the simulator
	was executed to load a file containing the machine instructions (aka
	machine code) from the assembler.
\item [$\ell$ 2] A message from the simulator indicating that it loaded the machine
	code into simulated memory at address 0.
\item [$\ell$ 3] This line shows the prompt from the debugger and the command
	\verb@t4@ that the user entered to request that the simulator trace 
	the execution of four instructions.
\item [$\ell$ 4-8] Prior to executing the first instruction, the state of the
	CPU registers is displayed.  
\item [$\ell$ 4] The values in registers 0, 1, 2, 3, 4, 5, 6 and 7 are printed 
	from left to right in \gls{bigendian}, \gls{hexadecimal} form.  
	The double-space gap in the middle of the line is a reference 
	to make it easier to visually navigate across the line without being
	forced to count the values from the far left when seeking the value 
	of, say, x5.
\item [$\ell$ 5-7] The values of registers 8--31 are printed.
\item [$\ell$ 8] The {\em program counter} (\reg{pc}) register is printed.  
	It contains the address of the instruction that the CPU will execute.  
	After each instruction, the \reg{pc} will either advance four bytes 
	ahead or be set to another value by a branch instruction as discussed above.
\item [$\ell$ 9] A four-byte instruction is fetched from memory at the address
	in the \reg{pc} register, is decoded and printed.  From left to right
	the fields shown on this line are:

	\begin{itemize}

	\item [00000000] The memory address from which the instruction was
		fetched.  This address is displayed in \gls{bigendian},
		\gls{hexadecimal} form.
	\item [00000e13] The machine code of the instruction displayed in 
		\gls{bigendian}, \gls{hexadecimal} form.
	\item [addi] The mnemonic for the machine instruction.
	\item [x28] The \reg{rd} field of the addi instruction.  
	\item [x0] The \reg{rs1} field of the addi instruction that
		holds one of the two addends of the operation.
	\item [0] The \reg{imm} field of the addi instruction that
		holds the second of the two addends of the operation.
	\item [\# \ldots] A simulator-generated comment that explains
		what the instruction is doing.  For this instruction it indicates 
		that \reg{x28} will have the value zero stored into it as a result 
		of performing the addition: $0+0$.
	\end{itemize}

\item [$\ell$ 10-14] These lines are printed as the prelude while tracing the
	second instruction. Lines 7 and 13 show that \reg{x28} has changed
	from \verb@f0f0f0f0@ to \verb@00000000@ as a result of executing the
	first instruction and lines 8 and 14 show that the \reg{pc} has 
	advanced from zero (the location of the first instruction) to 
	four, where the second instruction will be fetched.  None of the
	rest of the registers have changed values.
\item [$\ell$ 15] The second instruction decoded executed and described.  
	This time register \reg{x29} will be assigned a value.
\item [$\ell$ 16-27] The third and fourth instructions are traced.
\item [$\ell$ 28] Tracing has completed. The simulator prints its prompt
	and the user enters the `r' command to see the register state
	after the fourth instruction has completed executing.
\item [$\ell$ 29-33] Following the fourth instruction it can be observed
	that registers \reg{x28}, \reg{x29}, \reg{x30} and \reg{x31} 
	have been set to zero and that the \reg{pc} has advanced from
	zero to four, then eight, then 12 (the hex value for 12 is c)
	and then to 16 (which, in hex, is 10). 
\item [$\ell$ 34] The simulator exit command `x' is entered by the user and
	the terminal displays the shell prompt.

\end{itemize}
